home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 November / CPNL0711.ISO / admin / secure / Tor - Privoxy - Vidalia.exe / Tor / Documents / dir-spec-v1.txt < prev    next >
Text File  |  2007-08-30  |  14KB  |  316 lines
  1. $Id: dir-spec-v1.txt 9683 2007-02-28 18:08:58Z nickm $
  2.  
  3.                          Tor Protocol Specification
  4.  
  5.                               Roger Dingledine
  6.                                Nick Mathewson
  7.  
  8. 0. Prelimaries
  9.  
  10.   THIS SPECIFICATION IS OBSOLETE.
  11.  
  12.   This document specifies the Tor directory protocol as used in version
  13.   0.1.0.x and earlier.  See dir-spec.txt for a current version.
  14.  
  15. 1. Basic operation
  16.  
  17.   There is a small number of directory authorities, and a larger number of
  18.   caches.  Client and servers know public keys for the directory authorities.
  19.   Tor servers periodically upload self-signed "router descriptors" to the
  20.   directory authorities.  Each authority publishes a self-signed "directory"
  21.   (containing all the router descriptors it knows, and a statement on which
  22.   are running) and a self-signed "running routers" document containing only
  23.   the statement on which routers are running.
  24.  
  25.   All Tors periodically download these documents, downloading the directory
  26.   less frequently than they do the "running routers" document.  Clients
  27.   preferentially download from caches rather than authorities.
  28.  
  29. 1.1. Document format
  30.  
  31.   Router descriptors, directories, and running-routers documents all obey the
  32.   following lightweight extensible information format.
  33.  
  34.   The highest level object is a Document, which consists of one or more
  35.   Items.  Every Item begins with a KeywordLine, followed by one or more
  36.   Objects. A KeywordLine begins with a Keyword, optionally followed by
  37.   whitespace and more non-newline characters, and ends with a newline.  A
  38.   Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  39.   An Object is a block of encoded data in pseudo-Open-PGP-style
  40.   armor. (cf. RFC 2440)
  41.  
  42.   More formally:
  43.  
  44.     Document ::= (Item | NL)+
  45.     Item ::= KeywordLine Object*
  46.     KeywordLine ::= Keyword NL | Keyword WS ArgumentsChar+ NL
  47.     Keyword = KeywordChar+
  48.     KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
  49.     ArgumentChar ::= any printing ASCII character except NL.
  50.     WS = (SP | TAB)+
  51.     Object ::= BeginLine Base-64-encoded-data EndLine
  52.     BeginLine ::= "-----BEGIN " Keyword "-----" NL
  53.     EndLine ::= "-----END " Keyword "-----" NL
  54.  
  55.     The BeginLine and EndLine of an Object must use the same keyword.
  56.  
  57.   When interpreting a Document, software MUST reject any document containing a
  58.   KeywordLine that starts with a keyword it doesn't recognize.
  59.  
  60.   The "opt" keyword is reserved for non-critical future extensions.  All
  61.   implementations MUST ignore any item of the form "opt keyword ....." when
  62.   they would not recognize "keyword ....."; and MUST treat "opt keyword ....."
  63.   as synonymous with "keyword ......" when keyword is recognized.
  64.  
  65. 2. Router descriptor format.
  66.  
  67.   Every router descriptor MUST start with a "router" Item; MUST end with a
  68.   "router-signature" Item and an extra NL; and MUST contain exactly one
  69.   instance of each of the following Items: "published" "onion-key" "link-key"
  70.   "signing-key" "bandwidth".  Additionally, a router descriptor MAY contain
  71.   any number of "accept", "reject", "fingerprint", "uptime", and "opt" Items.
  72.   Other than "router" and "router-signature", the items may appear in any
  73.   order.
  74.  
  75.   The items' formats are as follows:
  76.    "router" nickname address ORPort SocksPort DirPort
  77.  
  78.       Indicates the beginning of a router descriptor.  "address"
  79.       must be an IPv4 address in dotted-quad format. The last
  80.       three numbers indicate the TCP ports at which this OR exposes
  81.       functionality. ORPort is a port at which this OR accepts TLS
  82.       connections for the main OR protocol; SocksPort is deprecated and
  83.       should always be 0; and DirPort is the port at which this OR accepts
  84.       directory-related HTTP connections.  If any port is not supported,
  85.       the value 0 is given instead of a port number.
  86.  
  87.    "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed
  88.  
  89.       Estimated bandwidth for this router, in bytes per second.  The
  90.       "average" bandwidth is the volume per second that the OR is willing
  91.       to sustain over long periods; the "burst" bandwidth is the volume
  92.       that the OR is willing to sustain in very short intervals.  The
  93.       "observed" value is an estimate of the capacity this server can
  94.       handle.  The server remembers the max bandwidth sustained output
  95.       over any ten second period in the past day, and another sustained
  96.       input.  The "observed" value is the lesser of these two numbers.
  97.  
  98.    "platform" string
  99.  
  100.       A human-readable string describing the system on which this OR is
  101.       running.  This MAY include the operating system, and SHOULD include
  102.       the name and version of the software implementing the Tor protocol.
  103.  
  104.    "published" YYYY-MM-DD HH:MM:SS
  105.  
  106.       The time, in GMT, when this descriptor was generated.
  107.  
  108.    "fingerprint"
  109.  
  110.       A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded
  111.       in hex, with a single space after every 4 characters) for this router's
  112.       identity key. A descriptor is considered invalid (and MUST be
  113.       rejected) if the fingerprint line does not match the public key.
  114.  
  115.       [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  116.        be marked with "opt" until earlier versions of Tor are obsolete.]
  117.  
  118.    "hibernating" 0|1
  119.  
  120.       If the value is 1, then the Tor server was hibernating when the
  121.       descriptor was published, and shouldn't be used to build circuits.
  122.  
  123.       [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  124.        be marked with "opt" until earlier versions of Tor are obsolete.]
  125.  
  126.    "uptime"
  127.  
  128.       The number of seconds that this OR process has been running.
  129.  
  130.    "onion-key" NL a public key in PEM format
  131.  
  132.       This key is used to encrypt EXTEND cells for this OR.  The key MUST
  133.       be accepted for at least XXXX hours after any new key is published in
  134.       a subsequent descriptor.
  135.  
  136.    "signing-key" NL a public key in PEM format
  137.  
  138.       The OR's long-term identity key.
  139.  
  140.    "accept" exitpattern
  141.    "reject" exitpattern
  142.  
  143.        These lines, in order, describe the rules that an OR follows when
  144.        deciding whether to allow a new stream to a given address.  The
  145.        'exitpattern' syntax is described below.
  146.  
  147.    "router-signature" NL Signature NL
  148.  
  149.        The "SIGNATURE" object contains a signature of the PKCS1-padded
  150.        hash of the entire router descriptor, taken from the beginning of the
  151.        "router" line, through the newline after the "router-signature" line.
  152.        The router descriptor is invalid unless the signature is performed
  153.        with the router's identity key.
  154.  
  155.    "contact" info NL
  156.  
  157.        Describes a way to contact the server's administrator, preferably
  158.        including an email address and a PGP key fingerprint.
  159.  
  160.    "family" names NL
  161.  
  162.        'Names' is a whitespace-separated list of server nicknames. If two ORs
  163.        list one another in their "family" entries, then OPs should treat them
  164.        as a single OR for the purpose of path selection.
  165.  
  166.        For example, if node A's descriptor contains "family B", and node B's
  167.        descriptor contains "family A", then node A and node B should never
  168.        be used on the same circuit.
  169.  
  170.    "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  171.    "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  172.  
  173.        Declare how much bandwidth the OR has used recently. Usage is divided
  174.        into intervals of NSEC seconds.  The YYYY-MM-DD HH:MM:SS field defines
  175.        the end of the most recent interval.  The numbers are the number of
  176.        bytes used in the most recent intervals, ordered from oldest to newest.
  177.  
  178.        [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
  179.         be marked with "opt" until earlier versions of Tor are obsolete.]
  180.  
  181. 2.1. Nonterminals in routerdescriptors
  182.  
  183.   nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
  184.  
  185.   exitpattern ::= addrspec ":" portspec
  186.   portspec ::= "*" | port | port "-" port
  187.   port ::= an integer between 1 and 65535, inclusive.
  188.   addrspec ::= "*" | ip4spec | ip6spec
  189.   ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
  190.   ip4 ::= an IPv4 address in dotted-quad format
  191.   ip4mask ::= an IPv4 mask in dotted-quad format
  192.   num_ip4_bits ::= an integer between 0 and 32
  193.   ip6spec ::= ip6 | ip6 "/" num_ip6_bits
  194.   ip6 ::= an IPv6 address, surrounded by square brackets.
  195.   num_ip6_bits ::= an integer between 0 and 128
  196.  
  197.   Ports are required; if they are not included in the router
  198.   line, they must appear in the "ports" lines.
  199.  
  200. 3. Directory format
  201.  
  202.   A Directory begins with a "signed-directory" item, followed by one each of
  203.   the following, in any order: "recommended-software", "published",
  204.   "router-status", "dir-signing-key".  It may include any number of "opt"
  205.   items.  After these items, a directory includes any number of router
  206.   descriptors, and a single "directory-signature" item.
  207.  
  208.     "signed-directory"
  209.  
  210.         Indicates the start of a directory.
  211.  
  212.     "published" YYYY-MM-DD HH:MM:SS
  213.  
  214.         The time at which this directory was generated and signed, in GMT.
  215.  
  216.     "dir-signing-key"
  217.  
  218.         The key used to sign this directory; see "signing-key" for format.
  219.  
  220.     "recommended-software"  comma-separated-version-list
  221.  
  222.         A list of which versions of which implementations are currently
  223.         believed to be secure and compatible with the network.
  224.  
  225.     "running-routers" whitespace-separated-list
  226.  
  227.         A description of which routers are currently believed to be up or
  228.         down.  Every entry consists of an optional "!", followed by either an
  229.         OR's nickname, or "$" followed by a hexadecimal encoding of the hash
  230.         of an OR's identity key.  If the "!" is included, the router is
  231.         believed not to be running; otherwise, it is believed to be running.
  232.         If a router's nickname is given, exactly one router of that nickname
  233.         will appear in the directory, and that router is "approved" by the
  234.         directory server.  If a hashed identity key is given, that OR is not
  235.         "approved".  [XXXX The 'running-routers' line is only provided for
  236.         backward compatibility.  New code should parse 'router-status'
  237.         instead.]
  238.  
  239.     "router-status" whitespace-separated-list
  240.  
  241.         A description of which routers are currently believed to be up or
  242.         down, and which are verified or unverified.  Contains one entry for
  243.         every router that the directory server knows.  Each entry is of the
  244.         format:
  245.  
  246.               !name=$digest  [Verified router, currently not live.]
  247.               name=$digest   [Verified router, currently live.]
  248.               !$digest       [Unverified router, currently not live.]
  249.           or  $digest        [Unverified router, currently live.]
  250.  
  251.         (where 'name' is the router's nickname and 'digest' is a hexadecimal
  252.         encoding of the hash of the routers' identity key).
  253.  
  254.         When parsing this line, clients should only mark a router as
  255.         'verified' if its nickname AND digest match the one provided.
  256.  
  257.     "directory-signature" nickname-of-dirserver NL Signature
  258.  
  259.   The signature is computed by computing the digest of the
  260.   directory, from the characters "signed-directory", through the newline
  261.   after "directory-signature".  This digest is then padded with PKCS.1,
  262.   and signed with the directory server's signing key.
  263.  
  264.   If software encounters an unrecognized keyword in a single router descriptor,
  265.   it MUST reject only that router descriptor, and continue using the
  266.   others.  Because this mechanism is used to add 'critical' extensions to
  267.   future versions of the router descriptor format, implementation should treat
  268.   it as a normal occurrence and not, for example, report it to the user as an
  269.   error.  [Versions of Tor prior to 0.1.1 did this.]
  270.  
  271.   If software encounters an unrecognized keyword in the directory header,
  272.   it SHOULD reject the entire directory.
  273.  
  274. 4. Network-status descriptor
  275.  
  276.   A "network-status" (a.k.a "running-routers") document is a truncated
  277.   directory that contains only the current status of a list of nodes, not
  278.   their actual descriptors.  It contains exactly one of each of the following
  279.   entries.
  280.  
  281.      "network-status"
  282.  
  283.         Must appear first.
  284.  
  285.      "published" YYYY-MM-DD HH:MM:SS
  286.  
  287.         (see section 3 above)
  288.  
  289.      "router-status" list
  290.  
  291.         (see section 3 above)
  292.  
  293.      "directory-signature" NL signature
  294.  
  295.         (see section 3 above)
  296.  
  297. 5. Behavior of a directory server
  298.  
  299.   lists nodes that are connected currently
  300.   speaks HTTP on a socket, spits out directory on request
  301.  
  302.   Directory servers listen on a certain port (the DirPort), and speak a
  303.   limited version of HTTP 1.0. Clients send either GET or POST commands.
  304.   The basic interactions are:
  305.     "%s %s HTTP/1.0\r\nContent-Length: %lu\r\nHost: %s\r\n\r\n",
  306.       command, url, content-length, host.
  307.     Get "/tor/" to fetch a full directory.
  308.     Get "/tor/dir.z" to fetch a compressed full directory.
  309.     Get "/tor/running-routers" to fetch a network-status descriptor.
  310.     Post "/tor/" to post a server descriptor, with the body of the
  311.       request containing the descriptor.
  312.  
  313.     "host" is used to specify the address:port of the dirserver, so
  314.     the request can survive going through HTTP proxies.
  315.  
  316.